Add Automated PyPI Publishing Workflow

Overview

This PR implements a GitHub Actions workflow that automatically publishes the mcp-proxy-for-aws package to PyPI when a new release is created. The workflow ensures code quality through automated testing, validates version formatting, builds distribution packages, and securely publishes to PyPI using API token authentication.

Changes

New Files

• .github/workflows/pypi-publish-on-release.yml - Main publishing workflow

Workflow Architecture

The workflow consists of three sequential jobs that create a fail-fast pipeline:

release.published event
        ↓
   call-test-lint (reuses python.yml)
        ↓
      build (validate version + create packages)
        ↓
     deploy (publish to PyPI)

Key Features

1. Automated Testing Integration

• Reuses existing python.yml workflow to run unit tests before publishing
• Passes release target commit SHA to ensure correct code is tested
• Blocks publishing if any tests fail

2. Version Validation

• Extracts version from pyproject.toml using Python's tomllib
• Validates semantic versioning format (X.Y.Z)
• Fails build if version format is invalid
• Prevents publishing of improperly versioned releases

3. Secure Package Building

• Uses uv package manager (consistent with existing workflows)
• Creates both wheel and source distributions
• Uploads packages as workflow artifacts for auditability
• Runs on Python 3.10 (matches existing CI/CD)

4. PyPI Publishing with API Token

• Uses pypa/gh-action-pypi-publish@release/v1 official action
• Authenticates via PYPI_API_TOKEN secret
• Publishes to https://pypi.org/p/mcp-proxy-for-aws
• Includes environment configuration for deployment tracking

5. Security Best Practices

• Minimal permissions per job (principle of least privilege)
• Disables credential persistence during checkout
• Uses stable action versions (v4, v5)
• No hardcoded secrets or credentials in workflow files

Setup Requirements

Before this workflow can be used, the following setup is required:

1. PyPI API Token

1. Generate a PyPI API token at https://pypi.org/manage/account/token/
2. Add it as a repository secret named PYPI_API_TOKEN
3. Scope: "Entire account" initially, then project-specific after first upload

2. GitHub Environment (Optional but Recommended)

1. Go to Settings → Environments
2. Create environment named pypi
3. Optionally add protection rules (required reviewers, deployment branches)

Testing Strategy

Post-Release Verification

1. Monitor workflow execution in Actions tab
2. Verify package appears on PyPI
3. Test installation: pip install mcp-proxy-for-aws
4. Confirm installed version matches release tag

Usage

Creating a Release

1. Update version in pyproject.toml:

   [project]
   version = "1.0.0"

2. Commit and push changes:

   git add pyproject.toml
   git commit -m "Bump version to 1.0.0"
   git push origin main

3. Create and publish a GitHub release:

   • Go to Releases → Draft a new release
   • Create tag: v1.0.0 (matching the version)
   • Fill in release notes
   • Click "Publish release"

4. The workflow automatically:

   • Runs all tests
   • Validates version format
   • Builds distribution packages
   • Publishes to PyPI

Error Handling

The workflow handles various failure scenarios:

Design Decisions

Why API Token Instead of Trusted Publishing?

• User preference for token-based authentication
• Simpler initial setup (no PyPI publisher configuration needed)
• Works immediately after adding secret
• Can migrate to Trusted Publishing later if desired

Why Reuse python.yml?

• DRY principle - single source of truth for tests
• Automatic updates when test configuration changes
• Consistent test environment across workflows

Why Sequential Jobs?

• Fail-fast behavior saves compute resources
• Logical dependency chain (can't deploy without building)
• Clear workflow progression and debugging

Why uv for Building?

• Consistent with existing workflows
• Faster than traditional build tools
• Already specified as build system in project

Requirements Satisfied

This implementation satisfies all requirements from the specification:

• ✅ Req 1: Automatic triggering on release publication
• ✅ Req 2: Integration with existing test workflows
• ✅ Req 3: Version format validation (X.Y.Z)
• ✅ Req 4: Distribution package building with uv
• ✅ Req 5: Secure PyPI publishing with API token
• ✅ Req 6: Security best practices (minimal permissions, pinned actions)

Related Documentation

• PyPI Publishing Guide
• GitHub Actions Workflow Syntax
• pypa/gh-action-pypi-publish

Checklist

• Workflow file created and tested
• Test workflow for TestPyPI created
• Security best practices implemented
• Error handling documented
• Setup instructions provided
• All requirements satisfied
• PYPI_API_TOKEN secret added (requires maintainer access)
• PyPI environment created (optional)

Is this a breaking change? (Y/N)

• Yes
• No

Please add details about how this change was tested.

• Did integration tests succeed?
• If the feature is a new use case, is it necessary to add a new integration test case?

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.